Reading CPAN

Max Maischein

Frankfurt.pm

Overview

  • Will the talk help me?

  • Find modules

  • Install modules

  • Use modules

  • Examples

Who am I

  • Max Maischein

  • DZ BANK Frankfurt

  • Deutsche Zentralgenossenschaftsbank

  • Data Scientist

Leitmotiv

Experience is something you need most when you have it least

Audience

👪👪👪

  • You

  • ... at least a part of you

  • Hopefully a large part

Programmers

👨‍💻

  • You know how to program

  • Didn't install a module yourself

  • Didn't have a module installed for you

  • Need to suggest / use / rate a module

Module authors

👩‍💻

  • Improve the thematic parts of your module

  • Improve findability

  • Improve installability

  • Improve documentation and usability

Distinction

⚠️

  • No fixed list of modules (see Task::Kensho, Phalanx 100, ...)

  • No rating of modules

  • That's your job

  • My opinion is marked "🚨"

  • Decision assistance for CPAN

Result

  • Domain knowledge is the most important thing

  • ... and knowing where to look it up

  • CPAN is not that central

The problem

  • We need X

     1:  X = Single sign on
     2:  X = XML
     3:  X = whatever
  • We use Perl

  • There surely is something on CPAN

  • Isn't there something on CPAN?

Steps

👣

  1. Collect domain knowledge

  2. Rate modules

  3. Install modules

  4. Use modules

Collect domain knowledge

🤷

  • Learn the domain

  • Find the places of discussion (mailing list, website, FB group, ???)

  • Review existing approaches

  • Review existing programs and documentation

  • Review existing libraries

Karma

🤷🤷

  • Luck: More than one alternative

  • Bad luck: More than two alternatives

Domain knowledge

  • Are there standard test cases / standard use cases?

  • When was the last change to the domain? To the API?

Examples to approaches

  • Automatic vs manual for cars

  • SAX vs. DOM for XML Parsers

  • Document oriented vs. relational for databases

Find (Perl-specific) libraries

🔍

  • Google (without "Perl")

  • Google (with "Perl")

  • CPAN with keywords from the searches

  • StackOverflow

Rate modules

⭐⭐⭐⭐🌟

  • Hard part

  • "Should I use module/approach Y or Z for doing X?"

  • Web everywhere: No reasonable person wants to do X!

  • Stack Overflow: Closed as Opinion

  • Perlmonks.org: What problem do you want to solve?

  • Date of the discussion

Rate modules

⭐🌟

Rate it yourself:

  • Compare test suite against standard test cases (OpenSSL, OWASP Testsuite, ....)

  • Example: Javascript Frameworks: "To-Do app"

  • When was the last change to (module, API, topic)

  • Example: MIME::Lite

  • Bugs in bug tracker

Reading module documentation

🗎🗎🗎🗎🗎

Module documentation

🗎🗎🗎🗎🗎

POD Sections and what they mean

  • NAME

  • ABSTRACT

  • SYNOPSIS

  • SEE ALSO

NAME

Name of the module

CPAN Metadata

What's in a name?

  • The name puts you in a long tradition of similar names and expectations

  • The name describes you accurately

CPAN Families

  • "Acme" 🤡

  • "Simple" in nothing but the name (XML::Simple, Filter::Simple, ...)

  • But also: LWP::Simple, Keyword::Simple, ...

  • "Tiny" as alternative

ABSTRACT

Single line description

ABSTRACT

Single line description

Kavorka - function signatures with the lure of the animal

Data::Dumper - stringified perl data structures, suitable for both printing and eval

Filter::signatures - very simplistic subroutine signatures for Perl < 5.20

SYNOPSIS

Simplest use possible

SYNOPSIS

Simplest use possible

 1:    use My::Module 'frobnicate';
 2:    frobnicate('foo'); # outputs "bar"

SEE ALSO

🌏🌍🌎

Where to look for more information

CPAN and metacpan.org

Bug tracker

🐛

  • 🐞 Open bugs

  • Closed bugs

  • Kind of problems

Processual dependencies

✉️

  • License

  • Licenses of the dependencies

Technical dependencies

  • API Keys and their storage

  • System programs and -APIs (Win32::, C-Compiler at runtime)

  • Online-access during installation

  • Interaction with other modules (Source filter, event loop)

Interoperability

🗿🗿🗿

  • How all-encompassing is the solution?

  • How much of this do I need to use?

  • Interoperability

  • Event-loops (AnyEvent, Mojo, ... )

  • Threads vs. C libraries

Install module

📦️

Is it installed?

📦

 1:    ⌨️ perldoc -l The::Module

Is it installed?

📦

 1:    ⌨️ perldoc -l The::Module
 2:    No documentation found for "The::Module".

Is it installed?

📦

 1:    ⌨️ perldoc -l The::Module
 2:
 3:    ⌨️ perl -MThe::Module=99999999 -e1

Is it installed?

📦

 1:    ⌨️ perldoc -l The::Module
 2:
 3:    ⌨️ perl -MThe::Module=99999999 -e1
 4:    Can't locate The/Module.pm in @INC ...

Is it installed?

📦

 1:    ⌨️ perldoc -l The::Module
 2:
 3:    ⌨️ perl -MThe::Module=99999999 -e1
 4:
 5:    ⌨️ perl -MV=Filter::signatures

Is it installed?

📦

 1:    ⌨️ perldoc -l The::Module
 2:
 3:    ⌨️ perl -MThe::Module=99999999 -e1
 4:
 5:    ⌨️ perl -MV=Filter::signatures
 6:    Filter::signatures
 7:      C:\...\site\lib\Filter\signatures.pm: 0.10

Is it installed?

📦

 1:    ⌨️ perldoc -l The::Module
 2:
 3:    ⌨️ perl -MThe::Module=99999999 -e1
 4:
 5:    ⌨️ perl -MV=Filter::signatures
 6:
 7:    ⌨️ cpan -l

Is it installed?

📦

 1:    ⌨️ perldoc -l The::Module
 2:
 3:    ⌨️ perl -MThe::Module=99999999 -e1
 4:
 5:    ⌨️ perl -MV=Filter::signatures
 6:
 7:    ⌨️ cpan -l
 8:    # a looong list of all installed modules

Is it installed (authors)?

👩‍💻

  • 🚨 every step roughly halves the number of people who will complete the process

  • 🚨 No additional steps

  • 🚨 Provide ready-to-install packages

  • 🚨 Provide step-by-step installation documentation

  • 🚨 Try to get Travis CI running (OSX + Linux installation)

  • 🚨 Try to get Appveyor running (Windows)

Is it installed?

  • Strawberry Perl is not Perl

  • Red Hat Perl is not Perl

  • ActiveState Perl is not Perl

  • 🚨 Every direct prerequisite module should to be listed in Makefile.PL / META.* / Build.PL / cpanfile

  • Will bite you later

How to install a module

🖥️📦

Installing a module

  • 🌶️ Easy (don't)

  • 🌶️🌶️🌶️🌶️🌶️ Hard (Perl+Module)

Installing a module

🌶️

  • don't

  • It's installed already

    corelist That::Module

  • ask your sysadmin

  • Testrun in a VM or on throwaway Google cloud instance

     1:  https://console.cloud.google.com/cloudshell/editor?pli=1&shellonly=true

Installing a module

🌶️🌶️

  1. use OS package manager + sysadmin

  2. 🚨 Never use CPAN with the system perl

  3. ⌨️ apt-get install libwww-mechanize-chrome-perl

  4. ⌨️ ppm WWW::Mechanize::Chrome

Installing a module

🌶️🌶️🌶️

  1. Use local::lib with system Perl

  2. ⌨️ cpan

  3. Choose local::lib method

  4. ⌨️ cpan My::Module

Installing a module

🌶️🌶️🌶️🌶️

Install App::perlbrew and your own Perl

Compile your own Perl (Linuxish)

 1:  ⌨️ perlbrew init
 2:  ⌨️ perlbrew install 5.28

Install modules using cpan

Installing a module

🌶️🌶️🌶️🌶️🌶️

Install another Perl under /opt/perl

Compile your own Perl (Linuxish)

 1:  ⌨️ sh Configure -Dprefix=/opt/perl -de
 2:  ⌨️ make
 3:  ⌨️ make test
 4:  ⌨️ make install

Install modules using cpan

Using a module

📖

Using a module

📖 Read

  • the documentation

  • the examples in the documentation ( Spreadsheet::ParseExcel::Examples )

  • the links in the documentation (bare minimum the author thinks is needed)

Using a module

📖 Read

 1:  ⌨️ cpan
 2:  ⌨️ look That::Module
  • the examples in the distribution

  • the tests

  • Use the source, Luke

  • Ask the author

Thanks

🙏

Thanks

🙏

Questions? 🙋

Thanks

🙏

Questions? 🙋

Slides are online:

https://corion.net/talks/

Examples

Examples (blacklist, not-black-list):

Web frameworks

  • Dancer

  • Dancer2

  • Jifty

  • Mojolicious

  • CGI::Application

  • ... *

  • 🚨 None good

Examples

Sending mail

🚨 MIME::Lite

Examples

Templates

🚨 Use whatever your framework suggests

Examples

Examples (blacklist, not-black-list):

[ ] IP handling NetAddr::IP / alte Version

Examples

Examples (blacklist, not-black-list):

JSON

  • JSON

  • JSON::Tiny

  • JSON::XS

  • Cpanel::JSON::XS

  • Mojo::JSON

  • none ideal

Examples

Examples (blacklist, not-black-list):

YAML

  • YAML::Tiny

  • YAML::Syck

  • ...

  • 🚨 Ask Tina

Examples

Examples (blacklist, not-black-list):

XML

  • 🚨 XML::Twig (DOM-like)

  • 🚨 XML::LibXML (DOM)

  • 🚨 XML::Compile (write XML using XSD)

  • 🚨 Never XML::Simple

Examples

Config modules

Examples

  • AnyEvent

  • Mojolicious

  • Net::Async

  • POE

  • 🚨 Future

Beispiele

Examples (blacklist, not-black-list):

[ ] Internationalization

Beispiele

Examples (blacklist, not-black-list):

[ ] Authentication

Examples

Web Scraping/HTTP

  • 🚨 WWW::Mechanize + HTML::TreeBuilder

  • 🚨 WWW::Mechanize::Chrome

  • 🚨 Mojo::UserAgent

Examples

ORMs / SQL helpers

  • 🚨 (None)

  • Model the data access and operations as objects, not the data =back

Examples

Class builders

  • Moose

  • 🚨 Moo 2

  • Mojo::Object

  • 🚨 none encourage anything other than hashes-as-objects

SEE ALSO